The Datafile PD-CD 1 Issue 2

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _editors / editors / _stronged / !EXTHELP / EXTHELP / HELPDATA next >

Wrap

Text File | 1994-04-09 | 69KB | 1,905 lines

Wimp Extension <Info> ------------------ <Heap=>WimpExt_Heap> <Help> <Windows> <Icons> <Menus> <Pointer> <Borders> <Requester boxes> <Draw / Sprites=>SprDrw> <Saving / Loading=>SveLoad> <Misc Vital> <Misc Other> ------------------ <Star commands=>Star_Comms>WimpExt_Initialise &45780 => R0 = 14 R1 = <Task handle=>SWI.Wimp_Initialise> R2 = <Features flags=>WimpExt_Initialisea> (try 1875) \<= R0 = WimpExt version number * 100 R2 = pointer to WimpExt's sprite pool Must be called prior to using any other WimpExt calls. R0 must be 14 on entry. This is so that WimpExtension can work out what version the program thinks it is calling (so I can change the functionality of calls later whilst still retaining backwards-compatibility). (I have also come accross sugested values of 16 & 11 for R0 in the Manual file. 14 works with v2.17.) WimpExt_CloseDown &45781 => R0 = task handle MUST be called prior to the task exiting.WimpExt_SlabIcon &45782 R2 = window handle or 0 for slabbed icon R3 = icon handle If semi-automatic slabbing is enabled, then: R4 = 0 to pop out, any other to pop in To be called to force an icon to be slabbed (for example to slab the default action icon if RETURN is pressed). If semi-automatic slabbing is enabled then the icon will be popped in or out depending on R4, otherwise it will be popped in and then out again. If R2 is zero then the last icon to be slabbed in (either implicity or explicity) is used. Note that in this case the SWI might return an error (eg. if the window has been deleted), so use the X form of the SWI.WimpExt_Action (&45784) => R0 = task handle R1 = Wimp_Poll block R2 = Wimp_Poll reason code R0 = Wimp_Poll reason code (possibly altered) To be called immediately after <Wimp_Poll=>SWI.Wimp_Poll>, to perform actions such as slabbing icons and changing pointers. WimpExtension may alter the code returned - eg. if the user clicks in a requester window then the code will be translated before your program gets to see it. See also <WimpExt_PrePoll>.<WimpExt_CurrentTask =>_CurrentTask > &4578B R0 = task handle Exit: R0 = previous task handle Informs WimpExtension which task is currently active. Not needed if you have called <WimpExt_Initialise =>_Initialise >or <WimpExt_Action =>_Action >since the last Wimp_Poll. =>_Poll. >The previous user is returned in R0.WimpExt_AutoRedraw (&45798) => R1 = <Wimp_Poll=>SWI.Wimp_Poll> reason code 1 block This call can be used instead of the normal <Wimp_RedrawWindow=>SWI.Wimp_RedrawWindow>/<GetRectangle=>SWI.Wimp_GetRectangle> loop if the window doesn't contain any graphics drawn by your program. It does the equivalent of: SYS "Wimp_RedrawWindow",,q% TO flag% WHILE flag% SYS "<WimpExt_Redraw>",,q% SYS "Wimp_GetRectangle",,q% TO flag% ENDWHILE WimpExt_Redraw (&45783) => R1 = Wimp_RedrawWindow block To be called in the window redraw loop, to draw the 3D borders round icons. See also <WimpExt_AutoRedraw>.WimpExt_OpenWindowTop (&4578E) => R0 = window handle Opens the window whose handle is in R0, or brings it to the top if it is already open. If the 'Back' attribute is set then it opens it at the back instead. Calls <WimpExt_OpenLinked>, so linked windows are handled correctly.WimpExt_CentreWindow (&45799) => R1 = pointer to block: R1 + 0 visible area minimum x coordinate R1 + 4 visible area minimum y coordinate R1 + 8 visible area maximum x coordinate R1 + 12 visible area maximum y coordinate R1 + 28 window flags \<= Block contains altered coordinates This call shifts the x coordinates in the supplied block so that the window described would be centred horizontally on the screen. You can use this call before <Wimp_CreateWindow=>SWI.Wimp_CreateWindow> - eg: SYS "WimpExt_CentreWindow",,q% SYS "<Wimp_CreateWindow=>SWI.Wimp_CreateWindow>",,q% TO handle% or you can use it before <Wimp_OpenWindow=>SWI.Wimp_OpenWindow> - eg: SYS "WimpExt_CentreWindow",,q%+4 SYS "<Wimp_OpenWindow=>SWI.Wimp_OpenWindow>",,q% If you are using <WimpExt_LoadTemplates> then windows can be centred automatically for you (see description above). See also <WimpExt_CentreWindowV>.WimpExt_CentreWindowV (&457BE) => R1 = pointer to block: R1 + 0 visible area minimum x coordinate R1 + 4 visible area minimum y coordinate R1 + 8 visible area maximum x coordinate R1 + 12 visible area maximum y coordinate R1 + 28 window flags Exit: Block contains altered coordinates This call shifts the y coordinates in the supplied block so that the window described would be centred vertically on the screen. You can use this call before <Wimp_CreateWindow=>SWI.Wimp_CreateWindow> - eg: SYS "WimpExt_CentreWindowV",,q% SYS "<Wimp_CreateWindow=>SWI.Wimp_CreateWindow>",,q% TO handle% or you can use it before <Wimp_OpenWindow=>SWI.Wimp_OpenWindow> - eg: SYS "WimpExt_CentreWindowV",,q%+4 SYS "<Wimp_OpenWindow=>SWI.Wimp_OpenWindow>",,q% If you are using <WimpExt_LoadTemplates> then windows can be centred automatically for you (see description above). See also SYS <WimpExt_CentreWindow>WimpExt_OpenFullSize (&457A4) => R2 = window handle R3 = window to open behind (-1 = top, -2 = bottom) Opens the window to maximum size - ie. the same as clicking on the toggle icon.WimpExt_LoadTemplates (&4578C) => R0 = pointer to buffer for storing window handles R1 = pointer to user buffer for template (big enough for largest template) R2 = pointer to workspace for indirected icons R3 = pointer to end of workspace for indirected icons R4 = 256-byte font reference array (-1 for no fonts) R5 = pointer to filename of templates file R6 = pointer to sprite area control block (+1 for Wimp sprite pool) Loads in all the templates from the file whose name is pointed to by R5, and calles <Wimp_CreateWindow=>SWI.Wimp_CreateWindow> for each one. The value in R6 is placed in the window block at offset +64. Stores the window handles sequentially in the buffer pointed to by R0, in the order they are found in the templates file. On exit the buffer pointed to by R1 will contain the template for the last window in the file. The buffer for window handles should be big enough to store all the window handles, each of which is a word. For each window, if the word on entry is zero the window will be created as usual. Bits that are set have the following meanings: Bit Meaning if set ---------------------------------------------- 0 centre window horizontally 1 don't create window 2 centre window vertically Bit 1 is useful if you have the last window in the file as one that you want repeatedly, but you don't want it created at once.WimpExt_CheckWindowOpen (&4579D) R0 = window handle (or -3 for <requester=>WimpExt_OpenRequester> window) Exit: R0 = 0 if window closed, 1 if open Checks to see if the specified window is open.WimpExt_SetWindowTitle (&4579F) => R2 = window handle R3 = pointer to string Copies the string in R3 into the window whose handle is in R2. The title must be indirected. Updates the screen if necessary.WimpExt_OpenRequester (&457A6) => R2 = title (eg. 'Message from MyTask') R3 = text (eg. 'Document not saved. Save?') R4 = pointer to <block=>WimpExt_OpenRequestera> containing button definitons R5 = button to be used if 'Escape' is pressed (0-3) Opens a requester box with a title, a message and some buttons along the right-hand edge. The pointer is constrained to the requester window. The buttons may contain any text up to 8 characters. You can have up to 4 buttons. They are filled with the text specified from the bottom one (the default) upwards. If the text for a button is a null string then that button will not be created. Mouse_Click events to the requester window will be passed from <WimpExt_Action> filtered so that only Select and Adjust are passed through, the window handle is -3, and the icon handle will be 0-3. You can check whether the requester window is open by using <WimpExt_CheckWindowOpen>.WimpExt_CloseRequester (&457A7) Closes the requester window and releases the mouse pointer. This is done automatically if the user selects a button in the requester box, or presses Escape or Return. If the window wasn't open then no error is generated. See also <WimpExt_OpenRequester>WimpExt_LinkWindows (&45787) => R2 = main window handle R3 = sub-window handle R4 = flags bit meaning 0 clip linked window to the left of the main window 1 clip linked window to the right of the main window 2 clip linked window above the main window 3 clip linked window below the main window 4-30 reserved; MUST BE 0 31 link is hidden Will link two windows so the sub-window moves with the main window. Currently there is a limit of 16 linked windows - this may be removed in a later version. See also <WimpExt_UnLinkWindows>.WimpExt_OpenLinked (&45788) => R1 = Wimp_OpenWindow block To be used instead of <Wimp_OpenWindow=>SWI.Wimp_OpenWindow>. It does the same thing, but if the window is linked then it will handle the link. If the window is not linked, it has the same effect as Wimp_OpenWindow. See also <WimpExt_CloseLinked>.WimpExt_CloseLinked (&45789) => R1 = Wimp_CloseWindow block To be used instead of <Wimp_CloseWindow=>SWI.Wimp_CloseWindow>. It does the same thing, but if the window is linked then it will close the linked window as well. If the window is not linked, it has the same effect as Wimp_CloseWindow. See also <WimpExt_OpenLinked>WimpExt_UnLinkWindows (&4578A) => R2 = main window handle R3 = sub-window handle Will remove the link between the specified window and its subwindow. Note that this just removes the pointer in WimpExtension workspace, if the windows are on the screen they will remain there. You do not have to call UnLinkWindows before you exit - it is here so that you can unlink windows while your application is still running. See also <WimpExt_LinkWindows>.WimpExt_HideLink (&457A8) => R0 = main window handle R2 = sub-window handle Temporarily hides the link between the specified window and its sub-window. This is useful, for example, for removing toolboxes in such a way that they can be replaced later. Note that this call does no screen update - ie. the sub-window remains where it is. See also <WimpExt_UnHideLink>.WimpExt_UnHideLink (&457A9) => R0 = main window handle R2 = sub-window handle Unhides the previously hidden link. Note that this call does no screen update - ie. the sub-window remains where it is. See also <WimpExt_HideLink>WimpExt_ManualLink (&46389) => R2 = main window handle R3 = sub-window handle R4 = flags bit meaning 0 clip linked window to the left of the main window 1 clip linked window to the right of the main window 2 clip linked window above the main window 3 clip linked window below the main 4-30 reserved; MUST BE 0 31 link is hidden R5 = X offset between main and sub-window R6 = Y offset between main and sub-window Will link two windows so the sub-window moves with the main window. Currently there is a limit of 16 linked windows - this may be removed in a later version. See also <WimpExt_LinkWindows>.Window-type SWIs #Prefix WimpExt_ #Table 12 20 <Redraw> <AutoRedraw> ------------- <OpenWindowTop> <CentreWindow> <CentreWindowV> <OpenFullSize> <SetExtent> <OpenDialogue> ------------- <LoadTemplates> <LoadRAMTemplate> <CheckWindowOpen> <SetWindowTitle> <OpenRequester> <CloseRequester> -------------- <LinkWindows> <UnLinkWindows> <OpenLinked> <CloseLinked> <HideLink> <UnHideLink> <ManualLink> #EndTable Icon-type SWIs #Prefix WimpExt_ #Table 15 24 <3D icons=>3D> <SlabIcon> <PlotBorder> <BorderOp> ------------- <IconBarSprite> <IconBarText> ------------- <SetIconString> <SetIconStringN> <SetIcon> <GetIcon> <SetNumberIcon> <GetNumberIcon> <Auto inc/dec of icons=>WimpExt_AutoIncDec> <IncNumberIcon> <DecNumberIcon> ------------- <ViewIcon> <SetIconColour> <ShadeIcon> ------------ <MoveCaret> <MoveCaretIcon> <PutCaretIcon> <Key handling=>WimpExt_IconKey> ------------ <DragIcon> <Radio icons> #EndTableWimpExt_IconBarSprite (&45785) => R2 = -2 for left of iconbar, -1 for right R3 = pointer to sprite name R5 = icon button type (eg. 3) \<= R0 = icon handle Will place a sprite on the iconbar, returning the icon handle. Note that the sprite name is copied out of the memory block, which can be reused. Also note that the number in R5 is just the button type, not the flags. See also <WimpExt_IconBarText> and <Wimp_CreateIcon=>SWI.Wimp_CreateIcon>.WimpExt_IconBarText (&45786) => R2 = -2 for left of iconbar, -1 for right R3 = pointer to sprite name R4 = pointer to text (max. 128 chars inc. terminator) R5 = icon button type (eg. 3) \<= R0 = icon handle Will place a sprite on the iconbar, with a text message underneath, returning the icon handle. Note that the sprite name is copied out of the memory block, which can be reused, but the text remains where it is; this is so you can change the text after creating the icon. Also note that the number in R5 is just the button type, not the flags. See also <WimpExt_IconBarSprite> and <Wimp_CreateIcon=>SWI.Wimp_CreateIcon>.WimpExt_SetIconString (&4578D) => R0 = non-zero for ellipsis (only if enabled in <WimpExt_Initialise>) R2 = window handle R3 = icon handle R4 = pointer to string Copies the string pointed to by R2 into the specified indirected text icon, and updates the screen if necessary. If the caret was in the icon then it is moved to the end of the new string. Only updates the screen if anything was changed - ie. if the new string is the same as the old string then nothing will happen. If R0 is non-zero and bit 7 was set in R2 in <WimpExt_Initialise> and the string is longer than the icon can hold then the string will be post-fixed with '...'.WimpExt_SetIcon (&4578F) => R2 = window handle R3 = icon handle R4 = 0 to deselect icon, non-zero to select icon If bit 6 of R2 was set in <WimpExt_Initialise>: R4 = 0 to deselect icon, 1 to select icon, 2 to toggle icon \<= R0 = old state of icon (0 for unset, 1 for set) Selects the icon if R4 is non-zero, deselects it otherwise. Updates the screen if necessary. If bit 6 of R2 was set in WimpExt_Initialise then the alternative parameters are used as shown. If bit 9 of R2 was set in WimpExt_Initialise and you are setting the icon, then other icons in the same ESG will be unset. See also <WimpExt_GetIcon>.WimpExt_GetIcon (&45790) => R2 = window handle R3 = icon handle \<= R0 = 0 if icon is not selected, 1 if it is selected R3 = Word at <iconblock=>SWI.Wimp_IconBlock>+20 (ie. pointer to indirected text for indirected text icon) Detects whether the icon is selected, and returns 1 in R0 if it is, 0 otherwise. Also returns in R3 the value in the iconblock at offset 20. For an indirected text icon this will be a pointer to the text. See also <WimpExt_SetIcon>.WimpExt_SetNumberIcon (&45791) => R0 = base R2 = window handle R3 = icon handle R4 = value Converts the signed integer in R4 into a string and places it in the icon. Updates the screen as necessary. The base to be used is specified in R0 - it must be in the range 2-36. See also <WimpExt_GetNumberIcon>.WimpExt_GetNumberIcon (&45792) => R0 = default base R2 = window handle R3 = icon handle \<= R0 = value Converts the string in the icon to a signed integer and places it in R0. The base to be used by default is specified in R0 - it must be in the range 2-36. See also <WimpExt_SetNumberIcon>.WimpExt_IncNumberIcon (&45793) => R0 = base R2 = window handle R3 = icon handle R4 = maximum value R5 = step \<= R0 = new value Converts the string in the icon to an signed integer, adds the step, and puts it back. Updates the screen as necessary. The value will not go beyond the value passed in R4, and the new value is returned in R0. See also <WimpExt_DecNumberIcon>WimpExt_DecNumberIcon (&45794) => R0 = base R2 = window handle R3 = icon handle R4 = minimum value R5 = step \<= R0 = new value Converts the string in the icon to an signed integer, subtracts the step, and puts it back. Updates the screen as necessary. The value will not go beyond the value passed in R4, and the new value is returned in R0. See also <WimpExt_IncNumberIcon>Drag flags in R0 => R0 = bits meaning 0-1 Horizontal position: 00 = left 01 = middle 10 = right 11 = undefined 2-3 Vertical position: 00 = bottom 01 = middle 10 = top 11 = undefined 4-5 Mouse bounding box: 00 = whole screen 01 = constrain to parent window 10 = constrain to box pointed to by R5 11 = undefined 6 constrain sprite if set, otherwise constrain pointer 7 shadow if set 8 use DragASprite even if CMOS flag isn't set 9-31 reserved; MUST BE 0WimpExt_DragIcon (&4579A) => R0 = <flags=>WimpExt_DragFlags> R1 = pointer to sprite block, +1 for Wimp sprite area, 0 to use dash box R2 = window handle R3 = icon handle R4 = pointer to sprite name (if R1<>0) R5 = pointer to mouse bounding box (only if necessary - see flags) +00 xmin +04 ymin +08 xmax +12 ymax This SWI does one of two things. If the DragASprite module is loaded, and bit 1 of byte 28 of the CMOS RAM is set, and R1<>0 then it will use the DragASprite module as follows: Work out the parameters to 'DragASprite_Start' and call it. If this produces an error then try again with dash box as described below. Otherwise it makes an ordinary rotating dash box as follows: Work out the parameters to 'Wimp_DragBox' and call it. Bits 0-3 and 7 of the flags are ignored. If you are using this SWI at any time with R1<>0 then remember to call XDragASprite_Stop at appropriate points. You MUST use the X form of the SWI, and you must ignore errors.WimpExt_PutCaretIcon (&4579B) R2 = window handle R3 = icon handle Works out the length of the text icon specified and calls <Wimp_SetCaretPosition=>SWI.Wimp_SetCaretPosition> to position the caret at the end of the string.WimpExt_SetIconStringN (&457A0) => R0 = non-zero for ellipsis (only if enabled in <WimpExt_Initialise>) R2 = window handle R3 = icon handle R4 = pointer to string Copies the string pointed to by R2 into the specified indirected text icon, and updates the screen if necessary. If the string is longer than the size of the buffer then the right-hand end of the string is copied (as opposed to the left-hand end, which is the case if you use <WimpExt_SetIconString>). If the caret was in the icon then it is moved to the end of the new string. If R0 is non-zero and bit 7 was set in R2 in WimpExt_Initialise and the string is longer than the icon can hold then the string will be pre-fixed with '...'.WimpExt_SetIconColour (&457B0) => R2 = window handle R3 = icon handle R4 = foreground colour (0-15 or -1 to keep the same) R5 = background colour (0-15 or -1 to keep the same) \<= R0 = old foreground colour + old background colour * 16 Changes the specified icon's colour(s). If there is no change then the icon is not updated (ie. it doesn't flicker). This call will now work for anti-aliased fonts, but the icon MUST have an 'F' validation command, as the Wimp needs this to specify the icon's colour.WimpExt_ShadeIcon (&457B1) => R2 = window handle R3 = icon handle R4 = 0 to unshade icon, non-zero to shade icon If bit 6 of R2 was set in <WimpExt_Initialise>: R4 = 0 to unshade icon, 1 to shade icon, 2 to toggle shade flag \<= R0 = old state of icon (0 for unshaded, 1 for shaded) Shades the icon if R2 is non-zero, unshades it otherwise. Updates the screen if necessary. If the caret was in the icon and you are telling WimpExtension to shade it then the caret is removed (disowned). If bit 6 of R2 was set in WimpExt_Initialise then the alternative parameters are used as shown.WimpExt_ViewIcon (&4638B) => R0 = movement type: 0 = scroll window minimum amount necessary 1 = centre icon in window (only if it's currently outside the window) 2 = choose 0 or 1 depending on how far outside the window the icon is R2 = window handle (or -1 for caret window and icon) R3 = icon handle (if R2<>-1) Checks to see if the specified icon is in the portion of the window which is visible on the screen, and scrolls the window to display it if it isn't. If R2=-1 then the icon containing the caret (if if belongs to your task) is used. R0=2 is the recommended movement type to use.WimpExt_MoveCaretIcon (&46384) => R2 = window handle R3 = icon handle Moves the caret into the specified icon, keeping its vertical position as nearly unchanged as possible. If the caret is currently disowned then it is placed at the end of the string in the icon.WimpExt_SetExtent (&457B5) => R0 = window handle R1 = pointer to block +00 = new work area minimum x +04 = new work area minimum y +08 = new work area maximum x +12 = new work area maximum y Sets the work area extent of the specified window, altering the values to be whole pixels, and reopening the window (if already open) so that the change is reflected on the screen.WimpExt_MoveCaret (&457B6) => R0 = key R2 = window handle R3 = icon handle \<= R0 preserved if no action taken, 0 otherwise Moves the caret from its current writeable icon to the next one above or below (in number) if the key in R0 is up arrow (or shift-tab) or down arrow (or tab). If you set bit 8 of R2 on entry to <WimpExt_Initialise> then this SWI will be called automatically for you in <WimpExt_Action>, and the reason code translated to a null event if the key is processed.WimpExt_BorderOp (&46388) => R0 = <reason code=>WimpExt_BorderOpa> other registers as appropriate for reason code Peforms misc. border read operations.Codes for R0: 0 : <Get border number=>WimpExt_BorderOpb> 1 : <Get border width=>WimpExt_BorderOpc> 2 : <Get bounding box in registers=>WimpExt_BorderOpd> 3 : <Get bounding box in block=>WimpExt_BorderOpe>Get border number => R0 = 0 R1 = pointer to icon block \<= R0 = border number, or -1 if the icon has no 3D border Returns the number of the 3D border of the specified icon. -1 is returned if the icon has no 3D border.Get border width => R0 = 1 R2 = border number (0-6) \<= R0 = width in OS units, or 0 if R2 did not contain a valid border number Returns the width of the 3D border outside the icon's bounding box. 0 is returned if an invalid border type is specified.Get icon bounding box in registers => R0 = 2 R1 = pointer to <icon block=>SWI.Wimp_iconblock> \<= R2 = XMin R3 = YMin R4 = XMax R5 = YMax Returns the bounding box of the icon, including the 3D border if present. Read icon block with <Wimp_GetIconState=>SWI.Wimp_GetIconState>.Get bounding box in block => R0 = 3 R1 = pointer to icon block R2 = pointer to 16-byte block to receive bounding box \<= block + 0 = XMin block + 4 = YMin block + 8 = XMax block + 12 = YMax Returns the bounding box of the icon, including the 3D border if present.3D border types 0 : Standard 3D border. Used for headings and buttons. Pops in if clicked on. 1 : Ridged grouping border. Put it around things of a similar nature. 2 : Like 0, with a channel round it. Used for the default button (ie. the one that is pressed if you press RETURN). 3 : Wide border for writeable icons - leave the normal black border on the icon and make the background white. 4 : Popped in border - for things that are for information only. 5 : Trenched border - the opposite of border 1. Can be clicked on. Suggested use is as an alternate border 1. 6 : Title border - similar to border 0, but with two 'dents'. This border is designed to be used as the title of a group, with a border 1 icon behind it as the frame. If you add 8 to the border number, it will become inert - ie. it will ignore all mouse clicks and not pop in. Bordered icons should be filled if you want them to change colour when clicked on. If you want an icon which doesn't change colour when slabbed in and out unset the 'Filled' flag Click Shift-Adjust on the iconbar to see an example of this.3D icons 3D borders are controlled by the 'w' validation command: #Prefix 3D_ w <border number>,\<slabbing mask>,\<slabbing time>,\<top left colour>, \<bottom right colour>,\<popped in colour>,\<popped out colour>, \<channel colour> All the numbers apart from the border number are optional. The defaults are: wxx,4,15,4,0,1,14,12. These defaults can be changed by the user, using the star command '<WimpExt Defaults=>Star_Defaults>'. You can specify only some, eg: w2,4,20 or w2,,,,3.Auto incremtening / decrementing of icons If, as is often the case, you have a number in an indirected icon on the screen and you want the user to be able to alter it, it is nice to have bumper icons next to it as well as making it writeable. For this purpose, you can specify that an icon should decrement/increment another icon when clicked on in the validation string. The syntax of the command is: Syntax: wi\<icon>,\<minimum>,\<maximum>,\<step> The default values are: wixx,0,&7FFFFFFF,1. All the values are optional apart from the icon number. To make it decrement the icon instead, use a negative step value. If the user clicks with Adjust instead of Select then the icon will be incremented instead of decremented, or vice-versa.Menu SWI's <CreateMenu=>WimpExt_CreateMenu> <ReCreateMenu=>WimpExt_ReCreateMenu> <MenuWidth=>WimpExt_MenuWidth> ---------- <ShadeEntry=>WimpExt_ShadeEntry> <TickEntry=>WimpExt_TickEntry> ----------- <GetFontMenu=>WimpExt_GetFontMenu> <DecodeFontMenu=>WimpExt_DecodeFontMenu> -------------- <ColoursMenu=>WimpExt_ColoursMenu> <OpenDialogue=>WimpExt_OpenDialogue> WimpExt_ColoursMenu (&45797) => R0 = colour to be ticked R2 = 0 to have just colours, 1 to have extra option \<= R0 = pointer to colour menu Creates a colour menu (like Edit's 'Background' and 'Foreground' ones), making the text of each option black or white depending on the brightness of that colour in the current palette. If the value in R0 on entry is in the range 0-15 then that colour will be ticked in the menu. The call returns a pointer to the menu block (in RMA workspace). If the value in R2 on entry is 1 then a 17th option will be added, 'Transparent'. You can change the text of this by changing the menu block if you want (it's in RMA). The 17th option will be ticked if R0 on entry is 16.WimpExt_OpenDialogue (&4579C) => R2 = window handle R3 = X Offset R4 = Y Offset Opens the specified window using <Wimp_CreateMenu=>SWI.Wimp_CreateMenu> at the pointer position, offset by R3 and R4. The coordinates used are PointerX-R3,PointerY+R4.WimpExt_CreateMenu (&457AC) => R1 = pointer to menu structure, or window handle, or -1 to close menus R2 = menu X R3 = menu Y Exactly the same as <Wimp_CreateMenu=>SWI.Wimp_CreateMenu>, except that the parameters are stored so that, after you have processed the selection, if the user clicked ADJUST you can call <WimpExt_ReCreateMenu> to reopen the menu, or this can be done for you (see <WimpExt_Initialise>).WimpExt_ReCreateMenu (&457AD) Reopens the last menu opened with <WimpExt_CreateMenu>. Generates an error if the last operation was to close a menu, or if you have not called <WimpExt_CreateMenu> yet.WimpExt_ShadeEntry (&457AE) => R1 = pointer to menu structure R2 = number of option to shade/unshade (0...nn) R3 = 0 to unshade = any other to shade If bit 6 of R2 was set in <WimpExt_Initialise> then R3 = 0 to unshade entry = 1 to shade icon = 2 to toggle shaded flag \<= R0 = old state (0 for unshaded, 1 for shaded) Shades or unshades the specified menu entry. If bit 6 of R2 was set in <WimpExt_Initialise> then the alternative parameters are used as shown.WimpExt_TickEntry (&457AF) => R1 = pointer to menu structure R2 = number of option to tick/untick (0...nn) R3 = 0 to untick = any other to tick If bit 6 of R2 was set in <WimpExt_Initialise> then R3 = 0 to untick entry = 1 to tick entry = 2 to toggle tick flag \<= R0 = old state (0 for unticked, 1 for ticked) Ticks or unticks the specified menu entry. If bit 6 of R2 was set in <WimpExt_Initialise> then the alternative parameters are used as shown.WimpExt_MenuWidth (&46382) => R1 = pointer to menu structure This SWI scans through the specified menu, altering its width and the widths of all its submenus, so that all the menus are the minimum width possible while still displaying the text correctly (and neatly).WimpExt_GetFontMenu (&457B7) => R0 = 0 to unshade 'System font' entry = 1 to shade it R1 = pointer to menu title (12 chars max), or 0 for default title 'Font' \<= R1 = pointer to menu structure Reads in the list of fonts currently available and creates a hierarchial menu structure with all the fonts listed by family. 'System font' is also on the root menu. This menu structure is guaranteed to remain in the same place for as long as your task is active. The font list MAY be read in the first time you call WimpExt_GetFontMenu, or it may have been read in earlier. See also <WimpExt_DecodeFontMenu>. This SWI may only be called if you set bit 2 of R2 when you called <WimpExt_Initialise>.WimpExt_DecodeFontMenu (&457B8) => R0 = pointer to buffer for font name R1 = pointer to <Wimp_Poll=>SWI.Wimp_Poll> block, reason code Menu_Selection The font menu is decoded and the correct font name is placed in the buffer. If the user selects, for example, 'Trinity' of 'Trinity.xxx','Trinity.yyy' the submenus will be followed through, and the font name at the top of each menu used. See also <WimpExt_GetFontMenu>. This SWI may only be called if you set bit 2 of R2 when you called <WimpExt_Initialise>.WimpExt_LoadRAMTemplate (&457A5) => R1 = pointer to user buffer for window definition R2 = pointer to workspace for indirected icons R3 = pointer to end of workspace for indirected icons R4 = -1 for no fonts - fonts not supported at present R5 = pointer to template \<= R2 = pointer to end of workspace used (ie. first free byte) This call is similar to <Wimp_LoadTemplate=>SWI.Wimp_LoadTemplate> except that it uses templates in RAM. This is designed to be used in Module tasks, where you cannot have a separate Templates file. You would use the supplied 'FNtemplate' function to insert the template in your module, and then call WimpExt_LoadRAMTemplate to convert this to a window definition. At present fonts in templates are not supported - this shouldn't cause too much of a problem as I have never seen a program which uses this feature anyway.Borders #Table 8 12 #Prefix WimpExt_ <3D borders=>3D> <SlabIcon> <PlotBorder> ---------- <BorderOp> -------- <Redraw> <AutoRedraw> #EndTable WimpExt_PlotBorder (&457BD) => R0 = <reason code=>WimpExt_PlotBordera> Other registers as appropriate for R0 Like <Wimp_PlotIcon=>SWI.Wimp_PlotIcon>, except it just redraws the 3D border. R0 specifies how the coordinates and border type are to be specified. If bit 31 of R0 is set then the border will be plotted slabbed in.Reason codes for PlotBorder (&457BD) => R0 = 0 R1 = pointer to <icon block=>SWI.Wimp_IconBlock> R2 = window handle (or -1 for no window) R0 = 1 R1 = pointer to block: + 0 Minimum work area x coordinate + 4 Minimum work area y coordinate + 8 Maximum work area x coordinate + 12 Maximum work area y coordinate + 16 <Border type=>3D_border number> R2 = window handle (or -1 for no window)Requseter boxes #Prefix WimpExt_ #Table 4 20 <OpenRequester> <CloseRequester> -------------- <ControlImmediate> #EndTable Block for WimpExt_OpenRequester (&457A6) Text for default button (eg. 'Save') Text for button 1 (eg. 'Discard') Text for button 2 (eg. 'Cancel') ...WimpExt_ControlImmediate (&457B9) => R1 = <Reason code=>WimpExt_ControlImmediatea> Other registers as appropriate for R1 This SWI is for using windows like the <Wimp_ReportError=>SWI.Wimp_ReportError> window that are not multi-tasking. You can only have one 'immediate window' open at a time, it is always on top of the window pile, and you MUST NOT call '<Wimp_Poll=>SWI.Wimp_Poll>' while the immediate window is open. If you call WimpExt_PrePoll while an immediate window is open then it will be closed automatically - the Wimp does not know about immediate windows and the screen display would become corrupted if you kept an immediate window open over a call to <Wimp_Poll=>SWI.Wimp_Poll> or <Wimp_PollIdle=>SWI.Wimp_PollIdle>. Icon types currently supported are: sprite-only non-indirected text-only, all types Unknown icon types will be ignored.Reason codes for WimpExt_ControlImmediate (&457B9) => R1 = -1 <Close immediate window=>WimpExt_ControlImmediateb> 0 <Close immediate window=>WimpExt_ControlImmediateb> 1 <Check for mouse click=>WimpExt_ControlImmediatec> 2 <Open immediate requester and wait for mouse click=>WimpExt_ControlImmediated> 3 <Redraw icon=>WimpExt_ControlImmediatee> 4 <Slab icon=>WimpExt_ControlImmediatef> 5 <Limit pointer=>WimpExt_ControlImmediateg> 6 <Redraw icon's 3D border=>WimpExt_ControlImmediateh> 7 <Redraw icon=>WimpExt_ControlImmediatei> >= &8000 <Open immediate window=>WimpExt_ControlImmediatej>WimpExt_ControlImmediate (reason 1) WimpExt will check for mouse clicks on icons in the window. 3D icons will be slabbed automatically. -1 is returned if no icon was clicked on.WimpExt_ControlImmediate (reason 1) WimpExt will check for mouse clicks on icons in the window. 3D icons will be slabbed automatically. -1 is returned if no icon was clicked on.WimpExt_ControlImmediate (reason 2) It opens an 'immediate requester' and waits for a mouse click on one of the action buttons, or ESCAPE or RETURN. The icon clicked on is returned in R0. The rest of the registers are as for <WimpExt_OpenRequester>.WimpExt_ControlImmediate (reason 3) The icon in the immediate window whose handle is in R0 will be redrawn (presumably because you have changed the indirected data). The 3D border is not redrawn.WimpExt_ControlImmediate (reason 4) The icon whose handle is in R0 will be slabbed in or out depending on R2 - similar to <WimpExt_SlabIcon> for normal icons. If the specified icon handle is -1 and R2 is 0 then the currently slabbed icon (if any) is used.WimpExt_ControlImmediate (reason 5) The mouse rectangle is redefined to be the size of the immediate window - similar to <WimpExt_LimitPointer> for normal windows. Use <WimpExt_ReleasePointer> to release the pointer again afterwards.WimpExt_ControlImmediate (reason 6) The specified icon's 3D border is redrawn. Icon handle is passed in R0 (?)WimpExt_ControlImmediate (reason 7) The specified icon is drawn. You do not need to have an immediate window open to use this reason code. Icon handle is passed in R0 (?)WimpExt_ControlImmediate (reason =>&8000) An immediate window is created from the <Wimp_CreateWindow=>SWI.Wimp_CreateWindow> block pointed to by R1. Draw / Sprite #Prefix WimpExt_ #Table 7 17 <RedirectSprites> <IconBarSprite> <PlotSprite> <SpriteOp> -------- <DrawOp> <RedrawDraw> #EndTable WimpExt_RedirectSprites (&4638D) => R0 = pointer to sprite area control block, or +1 for Wimp sprite area R1 = pointer to <Wimp_CreateWindow=>SWI.Wimp_CreateWindow> block Sets the sprite area control block pointer of all the indirected, sprite-only icons in the <CreateWindow=>SWI.Wimp_CreateWindow> block to R0.WimpExt_PlotSprite (&457B2) This SWI has been replaced by SWI <WimpExt_SpriteOp> 0. This call will still be supported - it just passes the call on to <WimpExt_SpriteOp>.WimpExt_RedrawDraw (&457B3) This SWI has been replaced by SWI <WimpExt_DrawOp> 0, which is a lot better at displaying draw files than this one. This call will still be supported, but if you have written a program using it you are strongly recommended to change to <WimpExt_DrawOp>.WimpExt_SpriteOp (&46386) => R0 = <reason code=>WimpExt_SpriteOpa> R1 = sprite control block pointer R2 = sprite pointer Other registers as appropriate for reason code This SWI performs various operations on sprites, including displaying them onto the screen (or printer). Note that these calls need <ColourTrans=>SWI.ColourTrans_> if you are using them with 256-colour sprites. It is similar to <OS_SpriteOp=>SWI.OS_SpriteOp> in that: R0 + 256 for user sprite area, R2 points to sprite name + 512 for user sprite area, R2 points to sprite R1 = 1 for Wimp pool R2 = Pointer to sprite or sprite name as R0 Note that R1 & R2 are as here unless otherwise specified. Sprites in the system sprite area are not supported.Reason codes for WimpExt_SpriteOp (&46386) => R0 = 0 <Display sprite=>WimpExt_SpriteOp0> 1 <Get palette=>WimpExt_SpriteOp1> 2 <Make pixel translation table=>WimpExt_SpriteOp2> 3 <Make scaling table=>WimpExt_SpriteOp3> 4 <Display sprite scaled=>WimpExt_SpriteOp4> 5 <Copy sprite=>WimpExt_SpriteOp5> 6 <Copy sprite area=>WimpExt_SpriteOp6> 7 <Remove duplicate names=>WimpExt_SpriteOp7> 8 <Copy sprite area sprite by sprite=>WimpExt_SpriteOp8> 9 <Check if sprite needs to be transformed=>WimpExt_SpriteOp9> 10 <Global replace=>WimpExt_SpriteOp10>Get palette (reason 1) => R0 = 1 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name \<= R3 = pointer to sprite's palette, or 0 if it doesn't have one R4 = number of entries in palette Locates the specified sprite's palette.Display sprite (reason 0) => R0 = 0 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = x coordinate (OS units) R4 = y coordinate (OS units) R5 = <plot action=>SWI.OS_SpriteOpd> Plots the specified sprite on the screen. This call is mode-independent, so if necessary the sprite is changed size and/or the colours are chosen appropriately.Make pixel translation table (reason 2) => R0 = 2 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = pointer to block to contain table (1 byte per colour) \<= block contains pixel translation data Calculates a pixel translation table for displaying the specified sprite in the current mode. If the sprite has no palette then the desktop's colours are used.Make scaling table (reason 3) => R0 = 3 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = Pointer to 16-byte block to contain table \<= block contains scaling table Calculates a scaling table for displaying the specified sprite at normal size in the current mode.Display sprite scaled (reason 4) => R0 = 4 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = x coordinate (OS units) R4 = y coordinate (OS units) R5 = plot action R6 = pointer to <sprite scaling table=>SWI.OS_SpriteOpe> Plots the specified sprite on the screen, scaled according to the table. This call is mode-independent, so if necessary the sprite is changed size and/or the colours are chosen appropriately. The sprite is first scaled to be the correct size in the current mode, then the specified scaling table is used.Copy sprite (reason 5) => R0 = 5 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = pointer to destination sprite area or +1 for Wimp sprite pool Copies the specified sprite into the destination sprite area. Gives an error if there isn't enough room. Note that sprites with duplicate names will NOT be overwritten; you will end up with two sprites with the same name. Copy sprite area (reason 6) => R0 = 6 R1 = source sprite control block pointer or +1 for Wimp RMA sprite pool, or +2 for Wimp ROM sprite pool R2 = target sprite control block pointer or +1 for Wimp sprite pool Copies ALL the sprites from the source sprite area to the target sprite area. Gives an error if there isn't enough room. Note that sprites with duplicate names will NOT be overwritten; you will end up with two sprites with the same name. Remove duplicate names (reason 7) => R0 = 7 R1 = <Sprite area=>SWI.OS_SpriteOpb>, or +1 for Wimp sprite pool Checks for sprites with duplicate names. If any exist, all copies except the LAST one will be deleted. Copy sprite area sprite by sprite (reason 8) => R0 = 8 R1 = Source <Sprite area=>SWI.OS_SpriteOpb>, or +1 for Wimp RMA sprite pool, or +2 for Wimp ROM sprite pool R2 = Target <Sprite area=>SWI.OS_SpriteOpb>, or +1 for Wimp sprite pool Copies ALL the sprites from the source sprite area to the target sprite area. Gives an error if there isn't enough room. The sprites will be copied one by one, with duplicate sprite names removed before each copy. This means that this call, while being slower than '<Copy sprite area=>WimpExt_SpriteOp6>' followed by '<Remove duplicate names=>WimpExt_SpriteOp7>', often requires less free memory in the target sprite area.Check if sprite needs to be transformed (reason 9) => R0 = 9 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = mode to check for, or -1 for current mode \<= R0 = bit meaning if set 0 a pixel translation table would be needed 1 a scaling table would be needed 2-31 undefined; will be 0 if the sprite doesn't need transforming Checks whether the specified sprite needs to be <scaled=>WimpExt_SpriteOp3> or needs a <pixel translation table=>WimpExt_SpriteOp2> to be plotted correctly in the specified mode. If either of these things are required, other <WimpExt_SpriteOp> calls exist to calculate them for you.Global replace (reason 10) => R0 = 10 R1 = <Sprite area=>SWI.OS_SpriteOpb> R2 = Pointer to sprite or sprite name R3 = search colour R4 = replace colour Replaces all pixels of colour R3 with pixels of colour R4. This routine isn't very fast, but it works. Currently it won't work with 256-colour sprites.WimpExt_DrawOp (&46385) => R0 = <reason code=>WimpExt_DrawOpa> Other registers as appropriate for R0 This SWI performs various operations on Draw files, including rendering them onto the screen (or printer). This call has replaced <WimpExt_RedrawDraw>Reason codes for WimpExt_DrawOp (&46385) => R0 = 0 <Render draw file=>WimpExt_DrawOp0> 1 <Calculate bounding box=>WimpExt_DrawOp1> 2 <Register unknown object handler=>WimpExt_DrawOp2>Render draw file (reason 0) => R0 = 0 R1 = Pointer to <scale/pos table=>WimpExt_DrawOpb> R2 = pointer to first object (ie. beginning of Draw file+40) R3 = pointer to end of last object (ie. end of file) R4 = pointer to <graphics clip box=>WimpExt_DrawOpc>, or 0 for no clipping \<= R0 ù R2 corrupted if scaling is not 1:1 This call displays a draw file. Objects will be checked one by one to see if they are in the clipping area, and redrawn if they are. Currently the following objects are supported: 0 - font table 1 - text 2 - path 5 - sprite 6 - group 7 - tag This is all the objects specified in the RISC OS 2 PRMs, except for text AREA objects, which are hardly ever used and are very very complicated. Magnifying a draw file by more than about 8 times is probably not a good idea because rounding errors in the Draw module will start to become significant. Note that this call requires the <ColourTrans=>SWI.ColourTrans_> module. It also requires the FPEmulator module, if and only if the scaling is not 1:1. This call replacesáthe old SWI <WimpExt_RedrawDraw>, which should now not be used. (This call is much better anyway.)Scaling / position table: block + 00 = amount to multiply X by * 65536 block + 04 = 0 block + 08 = 0 block + 12 = amount to multiply Y by * 65536 block + 16 = X origin (OS units) block + 20 = Y origin (OS units) Graphics clipping box: block + 00 = XMin block + 04 = YMin block + 08 = XMax block + 12 = YMaxCalculate bounding box (Reason 1) => R0 = 1 R2 = pointer to first object R3 = pointer to end of last object \<= R4 = XMin (Draw units) R5 = YMin (Draw units) R6 = XMax (Draw units) R7 = YMax (Draw units) Calculates the bounding box of the specified objects. The coordinates are returned in Draw units (which are OS Units * 256). Grouped objects are not checked individually - the group's bounding box is used. If no objects with bounding boxes are in the set specified then R4-R7 on exit are undefined. Unknown object types will not be checked. (This call 'knows' all the types described in the RISC OS 2 PRMs.)Register unknown object handler (Reason 2) => R0 = 1 R2 = pointer to routine (or 0 for no unknown object handler) R3 = pointer to workspace This routine will be called if the Render Draw File code encounters an unknown object. The routine has the following entry and exit conditions: (SVC mode) => R2 = pointer to object R4 = pointer to scaling and position table R6 = clipping rectangle XMin (pretransformed) R7 = clipping rectangle YMin (pretransformed) R8 = clipping rectangle XMax (pretransformed) R9 = clipping rectangle YMax (pretransformed) R12 = your workspace pointer R13 = pointer to supervisor stack (at least 256 bytes guaranteed) R14 = return address \<= R1-R11,R13 preserved V flag set on error, with R0 pointing to standard error blockRadio icons There are a couple of validation commands for helping with radio icons. 'ws' allows icons to select and deselect other icons when clicked on, and 'wu' allows icons to shade and unshade other icons. Syntax: ws\<action>,\<icon>[,\<icon>][,\<icon>][,\<icon>]... The action code is as follows: 0 deselect specified icons 1 select specified icons 2 toggle specified icons The syntax is exactly the same for 'wu' except that the icons will be shaded instead of selected. You can specify several of these commands in one validation string - eg. 'ws1,4;ws2,5;ws0,1'.The Heap Manager A heap (as provided by WimpExtension) is a section of memory, in which there are several blocks of memory (how many & how large is up to the task). These blocks move about in memory, and so anchors are provided to keep track. Each block has an anchor, and !anchor%=block%. Block may be resized, freed, compacted, fixed etc. Please note that the task must provide the heap itself - DIM heap% 1000, for instance. WimpExt provides one multi-purpose heap managing call, which does different things depending on the reason code. Read the <Heap text file=>*Filer_Run \<ExtHelp$Dir\>.Heap> for more info.WimpExt_Heap (&457BA) => R0 = <reason code=>WimpExt_Heapa> Other registers as apropriate for R0 This call provides all the heap managing features, depending on R0. <Info on heaps in general=>WimpExt_HeapHelp>Reason codes for WimpExt_Heap (&457BA) => R0 = 0 <Initialise heap=>WimpExt_Heap0> 1 <Heap info=>WimpExt_Heap1> 2 <New block=>WimpExt_Heap2> 3 <Free unused memory=>WimpExt_Heap3> 4 <Resize block=>WimpExt_Heap4> 5 <Fast heap tidy=>WimpExt_Heap5> 6 <Slow optimal heap tidy=>WimpExt_Heap6> 7 <Get anchor=>WimpExt_Heap7> 8 <Fix heap (nested)=>WimpExt_Heap8> 9 <Unfix heap (ignore nesting)=>WimpExt_Heap9> 10 <Unfix heap (nested)=>WimpExt_Heap10> 11 <Add anchors=>WimpExt_Heap11> 12 <New block=>WimpExt_Heap12> 13 <Release memory, kill heap=>WimpExt_Heap13>Initialise heap (Reason 0) => R0 = 0 R1 = Base in memory of heap R2 = No. of anchors. Initialise a heap with X anchors in R2. More anchors may be added later with <reason code 11=>WimpExt_Heap11>, but it is much quicker to do it at the start.Heap info (Reason 1) => R0 = 1 \<= R2 = Size of largest unused area of memory in heap R3 = Total free memory R4 = Total size of heap R5 = No. of anchors created R6 = Current number of blocks This call gives misc. info about the heap.New block (Reason 2) => R0 = 2 R1 = 0 (unused) R2 = Size of block \<= R1 = anchor (0 if not enough free memory) This call create a new block returning 0 if there was not enough memory.Free memory used by block (Reason 3) => R0 = 3 R1 = anchor for block This call kills a block, and frees it's memory.Resize block (Reason 4) => R0 = 4 R1 = Anchor R2 = New size \<= R1 = Flag This call resizes a block, returning zero if there is no room.Features flags => R2 = bit meaning 0 Semi-automatic slabbing if set, automatic otherwise 1 Automatically recreate menus if set 2 Task wants to use font menus if set 3 Automatically compact <heap=>WimpExt_Heap> once a second if set 4 'Correct' radio icons if set 5 Semi-automatic help if set, automatic otherwise 6 Use alternative parameters for flag-setting SWIs if set 7 Use R0 of <WimpExt_SetIconStringN> 8 Automatically call <WimpExt_MoveCaret> 9 Unset other icons in ESG when setting icons 10 Automatically call <WimpExt_ViewIcon> after moving caret 11 Don't allow TAB for moving between writeable icons 12-31 reserved; MUST BE 0 If bit 1 of R2 is set then if the user selects a menu option with the ADJUST button then the menu will automatically be recreated when you next call <WimpExt_PrePoll> (assuming you used '<WimpExt_CreateMenu>' to create the menu, that is). If bit 2 of R2 is set then you are allowed to call <WimpExt_GetFontMenu> and <WimpExt_DecodeFontMenu> - you are NOT allowed to call them if you do not set bit 2. If bit 4 of R2 is set then the user won't be able to deselect all of a group of radio icons by clicking adjust on the selected icon.Fast tidy (Reason 5) => R0 = 5 This call makes a very fast, but non-optimal, compaction of the heap. If bit 3 of R2 is set on entry to <WimpExt_Initialise>, then this will automatically occur every <WimpExt_PrePoll>.Slow, optimal heap tidy (Reason 6) => R0 = 6 This call compacts the heap to it's minimum possible value, but is somewhat slower than <reason code 5=>WimpExt_Heap5>.Get anchor (Reason 7) => R0 = 7 R1 = block \<= R1 = anchor Use this call if your task needs to know the anchor of a block, of which it knows the position in memory.Fix heap (Reason 8) => R0 = 8 This call freezes the heap, so it cannot move in memory. To unfreeze, call with <reason code 10=>WimpExt_Heap10>, or <code 9=>WimpExt_Heap9> The difference is, code 10 should be called the same no. of times as code 8, or the heap will remain frozen if it is not called enough times. Code 9, however, does not care how many times code 8 has been called, and unfreezes the heap anyway: FOR i%=0 TO 10 SYS "WimpExt_Heap",8 : REM Freeze ... SYS "WimpExt_Heap",9 : REM Unfreeze NEXT Whereas code 9 would just be called once, after the loop. Unfix heap (Reason 9) => R0 = 9 This call simply unfixes the heap, regardless of how many times <reason 8=>WimpExt_Heap8> has been called.Unfix heap (Reason 10) This call unfixes the heap, but if <code 8=>WimpExt_Heap8> has been called more than once, it will not unfix it - to do so, it would have to be called the same number of times. See also <code 9=>WimpExt_Heap9>Add anchors (Reason 11) => R0 = 11 R1 = No. to add Add R1 extra anchors. This is quite slow, relative to doing it at the start with <code 0=>WimpExt_Heap0>.New block (Reason 12) => R0 = 12 \<= R1 = Anchor This call creates a new block, automatically creating a new anchor if necessary.Kill heap (Reason 13) => R0 = 13 This call kills a heap, freeing the memory it was using.Misc. vital #Table 8 14 #Prefix WimpExt_ <Initialise> <CloseDown> --------- <PrePoll> <Action> ------ <Redraw> <AutoRedraw> #EndTable WimpExt_PrePoll (&457B4) To be called immediately before <Wimp_Poll=>SWI.Wimp_Poll> or <Wimp_PollIdle=>SWI.Wimp_PollIdle>. This filters clicks from requester windows and the like, so they appear with proper values (-3 for requester window) etc.Saving / Loading data #Prefix WimpExt_ #Table 3 10 <DragIcon> <DataSave> <DataLoad> #EndTable WimpExt_DataSave (&457BC) => R0 = file length R1 = pointer to filename (pathname or leafname) R2 = file type R3 = pointer to data R4 = zero to allow files to be saved to your own task, non-zero otherwise R5 = pointer to Wimp_GetPointerInfo block if >=&8000, otherwise file will be saved to current mouse position \<= R0 = 0 if failed due to attempt to save to own task, non- zero otherwise Used to save a file from your program to a filer or to another task. When you receive the User_Drag_Box event after the user has dragged the icon to where they want it put, call WimpExt_DataSave to handle the data transfer. R5 allows you to use this call to save to a specified place - just use R5=0 if you want to save to the pointer position. If R4 is non-zero on entry, then if the user has dragged the file to a window or icon belonging to your task then no action will be taken, and R0 will be zero on exit. Otherwise, when the transfer has finished, WimpExtension will send you a message, number &45782, with the word at R1+20 having the following meaning: 0 = file not saved. Error block at R1+24 1 = file saved but is 'unsafe' (eg. saved to another task) 2 = file saved. Filename at R1+24WimpExt_DataLoad (&46383) => R0 = 0 : Load into heap block R1 = pointer to DataSave or DataLoad message block R2 = block pointer of block to receive file, or 0 to create new block R3 = offset in block to place file R0 = 1 : Load into fixed block R1 = pointer to DataSave or DataLoad message block R2 = pointer to block to receive file R3 = length of block Use this SWI to load files from the filer or other applications. If R0=0 then the file is loaded into a WimpExt_Heap block, and can be any length, memory permitting. If R0=1 then the file is loaded into a fixed area of memory, and will not be loaded if it exceeds the length of the area. When you receive the DataSave or DataLoad message, pass the block onto WimpExt_DataLoad, and the transfer will be handled automatically. As long as this SWI doesn't return an error, when the transfer has finished, WimpExtension will send you a message, number &45784, with the word at R1+20 having the following meaning: 0 = file not loaded. Error block at R1+28 1 = file transferred successfully from another task 2 = file loaded successfully from disc A pointer to the block's anchor is at R1+24, if it was loaded into a heap block. Otherwise a pointer to the area is at R1+24. If R1+20<>0 then the rest of the block contains: + 28 = length of file + 32 = load address of file + 36 = exec address of file + 40 = filename (leafname if transferred from task) Obviously you need to have initialised a <heap=>WimpExt_Heap> to use this SWI. Note that WimpExtension won't free the block if there's an error; your error handler must do this if appropriate. The load and exec addresses don't indicate the date if the file was transferred from another task (the relevant bits will all be zero).Pointer SWIs #Prefix WimpExt_ #Table 5 17 <LimitPointer> <ReleasePointer> ---------------- <SetPointer> <The 'wp' command> #EndTable ---------------- Click Adjust on the iconbar for an example of this.WimpExt_SetPointer (&45795) => R0 = pointer to sprite name in the Wimp sprite pool, or 0 to reset pointer If R0 >= &8000 (to change pointer) R2 = hotspot X R3 = hotspot Y Stores the old pointer palette, and changes the pointer palette and shape to the sprite specified in R0 (palette optional). The 'hotspot' is defined by the X and Y coordinates (pixels) in R2 and R3. If R0 is \< &8000 then it will reset the pointer to its original state. You don't need to check if the pointer is already reset or changed as WimpExtension will do this for you. Note that the pointer will keep changed until you specifically ask for it to be reset - ie. pointer changes over icons will be suspended, and the pointer will remain changed outside your window's workarea.WimpExt_LimitPointer (&457A2) => R0 = window handle Limits the mouse pointer to the visible area of the window specified. Note that if there are draggable objects within this area and these are used then the mouse rectangle is reset. It is also reset if there is a change of mode, eg. if the user presses F12 and then Return. See also <WimpExt_ReleasePointer>.WimpExt_ReleasePointer (&457A3) Releases the limits on the mouse pointer - ie. sets the mouse rectangle to be the entire screen. Note that this call resets the graphics origin and the graphics and text windows. See also <WimpExt_LimitPointer>.Help #Prefix WimpExt_ #Table 3 20 <SendHelp> <SendWimpHelp> <Interactive help=>WimpExt_InterHelp> #EndTable Auto-Interactive help Syntax:wh\<message> When the pointer is over the icon, Acorn's Help application would display the message specified. If you set bit 5 of R2 when you called <WimpExt_Initialise>, specifying 'semi-automatic' help then instead of sending the message to Help for you, WimpExtension will instead give YOU a <message=>WimpExt_HelpMessage>, &45783, giving you the suggested help string.Help message format The message format is as follows: + 0 40 + 16 &45783 + 20 mouse X + 24 mouse Y + 28 button state + 32 window handle (-1 for background, -2 for icon bar, -3 for requester window) + 36 icon handle + 40 suggested text You may notice that this is the same as message &502, with the message number changed and the suggested text tagged on the end. To send this on unchanged, you would use: SYS "<WimpExt_SendHelp>",q%+40,q%WimpExt_SendHelp (&457AA) => R0 = message text R1 = pointer to message block containing message of type &502 or &45783 Sends a reply to message type &502, with the specified text. The message will appear in Help's Interactive Help Window, or WimpHelp's Standard Help Window.WimpExt_SendWimpHelp (&457AB) => R2 = keyword R3 = filename Sends a message to WimpHelp, telling it to open a hypertext help window from a file as specified in R3, with the keyword as specified in R2.Misc Other #Table 8 14 #Prefix WimpExt_ <CurrentTask> <Divide> <CopyString> <FindLeaf> <MemCopy> <Sort> <MemMove> <Intersect> #EndTable WimpExt_CurrentTask (&4578B) => R0 = task handle \<= R0 = previous task handle Informs WimpExtension which task is currently active. Not needed if you have called WimpExt_Initialise or WimpExt_Action since the last Wimp_Poll. The previous user is returned in R0.WimpExt_Divide (&45796) => R2 = numerator R3 = denominator \<= R0 = result R2 = remainder Returns (R2 DIV R3) in R0 and (R2 MOD R3) in R2. Useful for calculating which area of window needs to be updated. An error is produced if R3 is zero on entry.WimpExt_CopyString (&4579E) => R2 = 'from' pointer R3 = 'to' pointer Copies the control-terminated string from R2 to R3. The string stored at R3 will be zero-terminated whatever the terminator was for the original string.WimpExt_MemCopy (&457BB) => R0 = 'from' address (word aligned) R1 = 'to' address (word aligned) R2 = length (not necessarily word aligned) \<= R0 preserved Copies an area of memory very quickly. Can cope with overlap, R0=R1 or R2=0.WimpExt_Sort (&46380) => R0 = number of objects to sort R1 = pointer to array of objects R2 = pointer to comparison routine R3 = workspace pointer for comparison procedure R4 = size of object R5 = address of temporary workspace of R4 bytes (only needed if R4>63) This SWI will sort an array of objects. It is very similar to the OS_HeapSort SWI, except that you can use it to sort an array of ANY object, rather than just arrays of pointers. R2 points to a routine which is entered, in SVC mode, as follows: R0 = address of object a R1 = address of object b R12 = value supplied to WimpExt_Sort in R3 R13 = supervisor stack R14 = return address The routine should compare the two objects and return, preserving all registers apart from R0,R1,R12 and R14, with flags set as follows: a\<b Z=0, C=0 a=b Z=1, C=1 a>b Z=0, C=1 The actual method of sorting is unspecified; suffice it to say it's fast... Although R5 doesn't have to be word-aligned, the sort will probably be faster if it is.WimpExt_MemMove (&46381) => R0 = from R1 = to R2 = size in bytes Copies R2 bytes from R0 to R1. R0 and R1 need not be word-aligned, and R2 need not be a multiple of 4. This SWI uses the optimised memory copying routine given in the RISC OS 2 PRMs. It does not cope with overlap (which is why it's separate from <WimpExt_MemCopy>).WimpExt_Intersect &46387 ------------------------------- => R0 = 0 : Boxes in registers: R2 = XMin1 R3 = YMin1 R4 = XMax1 R5 = YMax1 R6 = XMin2 R7 = YMin2 R8 = XMax2 R9 = YMax2 R0 = 1 : Boxes in blocks: R2 = pointer to XMin1,YMin1,XMax1,YMax1 R3 = pointer to XMin2,YMin2,XMax2,YMax2 \<= If they intersect:R0 = 1, C flag set If not :R0 = 0, C flag clear Checks whether the specified rectangles intersect.About Ext Help Original text (all 71k) by Jon Ribbens, of <DoggySoft>. Conversion to the StrongHelp format, code for Ext Help by David Rodgman.DoggySoft #indent 15 #sprite 0,0 doggy To contact DoggySoft please write to: DoggySoft Consumer Department, Furzefield House, Furzefield Road, Beaconsfield, Bucks, HP9 1PQ. Or ring (0494) 673222 The 'wp' command Pointer changes over icons are controlled by the 'wp' validation command. Syntax:wp\<pointer name>,\<x hotspot>,\<y hotspot> The x and y hotspots are optional. What happens is that when the pointer is over the icon it will changed to the named sprite. The 'hotspot' is the area that is the actual 'point' of the pointer. Apart from the following supplied standard pointers, the sprite must be in the Wimp sprite pool. Standard supplied pointers are: ptr_write (4,4) should be used over writeable icons ptr_menu (6,5) should be used over icons that lead to menus when clicked with SELECT ptr_direct (12,6) should be used for resizing objects ptr_hand (10,9) should be used for dragging objects ptr_cross (8,4) should be used for accurate pointing You can have <user pointers=>WimpExt_Pointerwpa> as well.User pointers Pointer sprites should be designed in mode 8, maximum size 32x32 pixels. You should be wary of using logical colour 2 in pointer sprites, as it doesn't work in high-res mono modes. The pointer can have a palette if you want it to. If you are in a hi-res mode then WimpExtension will try to use a sprite of name "\<pointer>22", and then try "\<pointer>" if that didn't work. Therefore you can supply hi-res pointers as well (they should be in mode 19).Key handling As it is often needed that RETURN do the same as clicking on the default icon (the one with border type 2), and also that the up and down arrow keys move to writeable icons above and below, WimpExtension will handle these keys for you. Simply include the validation code 'wr' in the writeable icon's validation string: Syntax:wr[RETURN icon number],[up icon number], [down icon number] The icons specified will be used when the user presses RETURN, up arrow (or shift-tab) and down arrow (or tab) respectively. If the icon specified is a writeable icon then the caret will be moved to that icon, otherwise WimpExtension will generate a fake Mouse_Click event for that icon, which will make it appear to your task as if the user clicked with button status %100 on the icon (the mouse coordinates given will be those of the caret). You may leave out any of the numbers in the syntax, if you do so then WimpExtension will not affect the handling of that key.Where to send blank cheques... David Rodgman Laurel Farm Upper Strode Winford Bristol BS18 8BGStar Commands <Desktop_WimpExtension=>Star_DeskWE> <WimpExt=>Star_WimpExt> <X=>Star_X>Desktop_WimpExtension Like many modules, Wimp Extension provides this SWI and then says: Do not use *Desktop_WimpExtension Do not use it...WimpExt_FindLeaf (&457A1) => R0 = pointer to pathname \<= R0 = pointer to leafname Finds the last occurence of '.' in the string pointed to by R0, and returns a pointer to the next character. eg. given 'scsi::HardDisc.$.first.second.last' it will return a pointer to 'last'. This can be useful for both extracting the leaf name, and for determining what directory the file is in (by poking a zero to (R0-1) - eg. MOV R2,#0 STRB R2,[R0,#-1] ).*X Syntax: *X \<command> The same as typing * \<command> from the command line, but all errors are ignored.*WimpExt Provides access to misc commands concerning the Wimp Extension module. Tasks will not need to use these, as they are for the user of WimpExtension as opposed to the programmer. Commands are: <WimpExt Defaults=>Star_Defaults> <WimpExt LoseTasks=>Star_LoseTasks> <WimpExt SpriteColours=>Star_SpriteCols>*WimpExt Defaults Sets the default colours, slabbing time, and sprite style. Syntax: Defaults \<bottom-right> \<top-left> \<in> \<channel> \<time> \<style> Sprite style - 0 = 3D, 1 = flat Some examples are: #Table 8 26 <Dark slabbing=>*\<ExtHelp$Dir\>.Defaults.DarkSlab> <Default=>*\<ExtHelp$Dir\>.Defaults.Default> <Flat=>*\<ExtHelp$Dir\>.Defaults.Flat> <Interface II style=>*\<ExtHelp$Dir\>.Defaults.I2Style> <Inverse=>*\<ExtHelp$Dir\>.Defaults.Inverse> <No colour change=>*\<ExtHelp$Dir\>.Defaults.NotSlab> <Official Acorn style=>*\<ExtHelp$Dir\>.Defaults.Official> <Risc OS 3.1 normal style=>*\<ExtHelp$Dir\>.Defaults.310> 4 0 2 12 15 0 4 0 14 12 15 0 7 7 7 0 15 0 6 0 14 12 15 0 0 4 14 12 15 0 4 0 1 12 15 0 3 0 3 12 15 0 3 0 14 12 15 0 #EndTable *WimpExt LoseTasks LoseTasks tells WimpExtension to forget all about any Wimp tasks that are currently registered with it. This is not usually a good idea, but some bugged programs can sometimes manage to crash without de-registering themselves, so it can be useful.*WimpExt SpriteColours SpriteColours sets some of the colours of some of the sprites in the WimpExtension sprite pool. Each parameter specifies the colour of the symbol in a different sprite. Syntax: *WimpExt SpriteColours \<radioon> \<opton> \<yes> \<no>